Virtual Files

Modules
	I/O routines
	Virtual file sources
	RAM virtual files
Data Structures
struct	VIRTUAL_FILE
struct	VIRTUAL_FILE_SOURCE
struct	OSL_VIRTUALFILENAME
Enumerations
enum	VF_OPEN_MODES { VF_O_READ, VF_O_READWRITE, VF_O_WRITE }
Functions
void	VirtualFileInit ()
VIRTUAL_FILE *	VirtualFileOpen (void *param1, int param2, int type, int mode)
int	VirtualFileClose (VIRTUAL_FILE *f)
int	VirtualFileRegisterSource (VIRTUAL_FILE_SOURCE *vfs)
OSL_VIRTUALFILENAME *	oslFindFileInVirtualFilenameList (const char *fname, int type)
void *	oslReadEntireFileToMemory (VIRTUAL_FILE *f, int *size)

---

Detailed Description

Virtual File support for OSLib. This API is meant to be an universal mean to manipulate every file source possible as you can define your own.

---

Enumeration Type Documentation

enum VF_OPEN_MODES

Enumeration describing the available file open modes. Please note that some sources do not support some modes like READWRITE or WRITE, in this case they'll fail when an attempt to open a file in one of these modes is made. The resulting file returned by VirtualFileOpen will be NULL.

Enumerator:

VF_O_READ	Read only.
VF_O_READWRITE	Read & Write.
VF_O_WRITE	Write only.

---

Function Documentation

void VirtualFileInit

(

)

Initializes the virtual filesystem. Done by default by OSLib, so there is no need to call it by yourself.

VIRTUAL_FILE* VirtualFileOpen	(	void *	param1,
		int	param2,
		int	type,
		int	mode
	)

Open a new file.

Parameters:

	param1	Pointer to a string representing the file name.
	type	File type. By default, can be: VF_MEMORY: read/write from a memory block VF_FILE: read from standard stdio routines.
	mode	One of VF_OPEN_MODES.

int VirtualFileClose

(

VIRTUAL_FILE *

f

)

Closes an open file.

int VirtualFileRegisterSource

(

VIRTUAL_FILE_SOURCE *

vfs

)

Adds a new file source to the virtual file system.

Parameters:

vfs

Must be a pointer to a valid VIRTUAL_FILE_SOURCE interface containing all your functions for handling the file source.

Returns:

Returns the identifier of your source or -1 if it has failed. You can then use this ID as a file type (parameter for VirtualFileOpen).

OSL_VIRTUALFILENAME* oslFindFileInVirtualFilenameList	(	const char *	fname,
		int	type
	)

Call this function in your virtual file source OPEN handler, if it's a RAM based device and param2 == 0 (means null size, impossible). It will return a UL_VIRTUALFILENAME where you can get a pointer to the data and their size. Note that the return value can be NULL if the file has not been found or an error occured (e.g. fname is NULL).

void* oslReadEntireFileToMemory	(	VIRTUAL_FILE *	f,
		int *	size
	)

Reads an entire file to memory and returns a pointer to the memory block. The block memory usage is stepped by 4 kB, so even a 1 kB file will take 16 kB, so this function is not recommended for opening a lot of small files. The bloc must be freed (using free) once you've finished with it!

Parameters:

	f	Pointer to an open virtual file.
	size	Pointer to an integer that will contain the number of bytes read from the file. Can be NULL (in this case the value is discarded).

int size;
VIRTUAL_FILE *f;
char *data;
//Open a file
f = VirtualFileOpen("test.txt", 0, VF_AUTO, VF_O_READ);
//Read it entirely to RAM
data = oslReadEntireFileToMemory(f, &size);
//Print each character
for (i=0;i<size;i++)
        oslPrintf("%c", data[i]);

---